'---------------------------------------------------------------------------------------------------
'TEXT FILE INPUT / OUTPUT
'---------------------------------------------------------------------------------------------------
'SUMMARY
'   Purpose:  A library of custom subroutines and functions to load text to/from a file.
'   Author:   Dustinian Camburides
'   Platform: QB64 (www.qb64.net)
'   Revision: 1.0
'   Updated:  5/9/2012
'---------------------------------------------------------------------------------------------------
'REVISION HISTORY
'   1.1: Added: [FREEFILE] function (rather than defaulting all file streams to #1).
'               [_FILEEXISTS] function (rather than error-trapping).
'   1.0: First working version.
'---------------------------------------------------------------------------------------------------
'PLANNED ENHNACEMENTS
'   Minor:
'       - None at this time.
'   Major:
'       - Add function to return all files in a folder (subfolders optional).
'       - Check to see if folders exist in [Output_File].
'---------------------------------------------------------------------------------------------------
'PROCEDURES
'   - FUNCTION Input_File$ (Path AS STRING)
'   - SUB Output_File (Text AS STRING, Path AS STRING)    
'---------------------------------------------------------------------------------------------------

FUNCTION Input_File$ (Path AS STRING)
    'SUMMARY:
        '[Input_File$] returns the text of the file at the [Path] location.
    'INPUT:
        'Path: The location of the file.
    'VARIABLES:
        DIM strLine AS STRING           'The current [Line] being added to the [File Text] string.
        DIM strFileText AS STRING       'The [File Text] of the [Input File].
        DIM intFileNumber AS INTEGER    'The number of the file.
    'INITIALIZE:
        strFileText = ""
    'PROCESSING:
        'If the file exists:
            IF _FILEEXISTS(Path) THEN
                'Open the input file:
                    intFileNumber = FREEFILE
                    OPEN Path FOR INPUT AS #intFileNumber
                        'While not at the end of the file...
                            WHILE NOT EOF(intFileNumber)
                                'Input a line ot text:
                                    LINE INPUT #intFileNumber, strLine
                                'If the line is not blank...
                                    IF LEN(strFileText) > 0 THEN
                                        'Add the [line feed] and [carriage return] characters and the [line] to the [file text]:
                                            strFileText = strFileText + CHR$(13) + CHR$(10) + strLine
                                    ELSE
                                        'Add the new line to the file text:
                                            strFileText = strLine
                                    END IF
                        'Next line...
                            WEND
                'Close the input file:
                    CLOSE #intFileNumber
            END IF
    'OUTPUT:
        Input_File$ = strFileText
END FUNCTION

SUB Output_File (Text AS STRING, Path AS STRING)
    'SUMMARY:
        '[Output_File] outputs the [Text} into a file at the [Path] location.
    'INPUT:
        'Text: The output string; the text that's being output to the [Path] location.
        'Path: The location of the file.
    'VARIABLES:
        DIM intFileNumber AS INTEGER    'The number of the file.
    'PROCESSING:
        'Open the output file:
            intFileNumber = FREEFILE
            OPEN Path FOR OUTPUT AS #intFileNumber
                'Print the text to the file:
                    PRINT #intFileNumber, Text
        'Close the output file:
            CLOSE #intFileNumber
END SUB
